home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 2: CDPD 1 / Almathera Ten on Ten - Disc 2: CDPD 1.iso / pd / 301-325 / 325 / fam / asdg-lms / low memory server < prev    next >
Text File  |  1995-03-14  |  13KB  |  298 lines
  1.  
  2.             ASDG Low Memory Server Documentation
  3.  
  4.             Copyright 1987 By  ASDG Incorporated
  5.         All Rights, Except Those Granted Herein, Reserved
  6.  
  7. 1. Terms Of Distribution
  8. -----------------------------------------------------------------------------
  9.  
  10. Permission for the non-commercial distribution of the ASDG Low Memory Server 
  11. is hereby granted. Non-commercial distribution is defined as distribution by
  12. user groups, individuals  not for  profit, public service public domain disk 
  13. distributors (eg: my friend Fred Fish). 
  14.  
  15. Any manufacturer of hardware  or  software is specifically enjoined from the
  16. public distribution of  any  part  of the Low Memory Server unless licensing
  17. by ASDG is received.
  18.  
  19. The Low Memory Server is specifically NOT in the public domain. 
  20.  
  21. 2. Commercial Licensing
  22. -----------------------------------------------------------------------------
  23.  
  24. ASDG encourages the commercial use of  the  Low  Memory Server provided that
  25. following provisions are affirmed  and  agreed upon by ASDG and the prospec-
  26. tive licensee.
  27.  
  28. (a) The licensee agrees to credit ASDG  Incorporated for the use of the Low
  29.     Memory Server in some reasonable visible fashion in the licensee's pro-
  30.     duct documentation,
  31. (b) The licensee agrees to furnish ASDG with a finished product as it would
  32.     be purchased by the consumer.
  33.  
  34. Should ASDG find it  necessary, a  licensing fee of no more than $50 (U.S.)
  35. may be required in addition to the above.This fee is a one time expense and
  36. shall be used to defray the cost of providing the license agreement.
  37.  
  38. 3. What Is The ASDG Low Memory Server
  39. -----------------------------------------------------------------------------
  40.  
  41. The ASDG Low Memory Server is a compact (900 bytes) shared library which al-
  42. lows arbitrary processes to  register their desire to be notified of impend-
  43. ing memory shortages.
  44.  
  45. The purpose of the LMS is to allow for the easy notification of applications
  46. that they should attempt to clean up or reduce  their memory consumption  or 
  47. face a complete absence of available memory.
  48.  
  49. For example, a graphics or sound editor may elect to be notified that memory
  50. is becoming scarce and  if  so  notified  will deallocate space used to hold
  51. sounds or graphics  no longer  in current use by the user but which were re-
  52. tained in ram as a performance  boost in the event that the user would elect
  53. to reuse the data at a later time.
  54.  
  55. The ASDG LMS provides a reliable low memory  notification service which will
  56. be tripped upon any failure  of  an AllocMem system call. Note: the ASDG LMS
  57. uses operating system mechanics  already  present in 1.2 - it does not alter
  58. or modify any system code - anywhere. Specifically, AllocMem is NOT touched.
  59.  
  60. Notification is performed  via the natural interprocess communications prim-
  61. itive available on the Amiga, the message.
  62.  
  63. Support for the ASDG LMS is intended to be coded into your application.  The
  64. remainder of this document is an explanation of how this is done.
  65.  
  66. 4. As A Programmer, What Do You Agree To Do?
  67. -----------------------------------------------------------------------------
  68.  
  69. You agree (by writing your code correctly) to the following things:
  70.  
  71. (a) You  will allocate and  initialize a message port to be used by the ASDG
  72.     LMS to notify you.
  73. (b) You will allocate  and initialize  a LowMemMsg  structure which  will be
  74.     used BY the ASDG LMS to notify you.
  75. (c) To be effective, you  agree  to  monitor your LMS message port in all of
  76.     your calls to Wait.
  77. (d) You agree to call DeRegLowMemReq when exiting, prior to closing the ASDG
  78.     LMS library.
  79. (e) You agree to close the ASDG LMS library when done.
  80. (f) You agree to reinitialize your LowMemMsg each time the ASDG LMS notifies
  81.     you of memory shortages.
  82. (g) You agree  to examine the return code from RegLowMemReq. This routine is
  83.     your interface  to the Low Memory Server registration list. It will tell
  84.     you if the message  port  name you  supplied has  already  been  used by
  85.     someone else.
  86.  
  87. If  you  fail  to do these things,  there isn't much point in using the ASDG
  88. LMS.
  89.  
  90. 5. The LMS Message Port
  91. -----------------------------------------------------------------------------
  92.  
  93. You must allocate and initialize  a  message port to which the LMS will send
  94. you its low memory notification message. You  may  do this in the usual way.
  95. However, you must be prepared to delete this message port and re-allocate it
  96. as many times as is needed to get a unique message port name.
  97.  
  98. After defining the message  port (with  a  name you hope will be unique) and
  99. defining a LowMemMsg  (see  later)  you will register your message port name
  100. with the ASDG  LMS  by  calling  RegLowMemReq. This call may return an error
  101. value indicating that the message port name  is  not unique. Your request to
  102. register with the LMS has been denied  and you must delete your message port
  103. and redefine one with another name (and  loop to the call to RegLowMemReq a-
  104. gain).
  105.  
  106. This ensures that only one port with any given  name will be registered with
  107. the LMS.
  108.  
  109. 6. The LowMemMsg
  110. -----------------------------------------------------------------------------
  111.  
  112. YOU have to  allocate  a  LowMemMsg structure. This will be the message that
  113. LMS uses to notify you of a low memory condition.
  114.  
  115. You define it rather than the LMS since if  the LMS  needs  to  get in touch
  116. with you, it is because there is a low  memory situation present. Hardly the
  117. time to go allocating message storage.
  118.  
  119. The LowMemMsg structure as defined in low-mem.h is as follows:
  120.  
  121.     struct LowMemMsg {
  122.         struct Message lm_msg;
  123.         long lm_flag;
  124.     };
  125.  
  126. This is simply a  usual message structure with a long word flag tagged on the
  127. end. The only  initialization YOU have to do is to set the lm_flag to a spec-
  128. ific value, LM_CONDITION_ACKNOWLEDGED. The  LMS will  initialize the  rest of
  129. the message for you.
  130.  
  131. Setting lm_flag  to LM_CONDITION_ACKNOWLEDGED is  crucial   to your receiving
  132. messages from the LMS. Immediately  prior  to  sending  you a message the LMS
  133. will (after verifying  that  your registered message port exists) interrogate
  134. your lm_flag. If it is not set to LM_CONDITION_ACKNOWLEDGED then the LMS will
  135. not send you the message.
  136.  
  137. You are specifically NOT to Reply  to  the  message you receive from the LMS.
  138. The LMS is being run directly from  a failing AllocMem call by someone else's
  139. program. To prevent  the possibility  of a  program NOT replying to the LMS's
  140. message (and thus deadlocking the system) I use the LM_CONDITION_ACKNOWLEDGED
  141. value in lm_flag to signify that your process has acknowledged the receipt of
  142. its previous low memory message.
  143.  
  144. Repeat - DO NOT REPLY TO THE LOW MEMORY MESSAGE - SET lm_flag INSTEAD! Here's
  145. the definition of LM_CONDITION_ACKNOWLEDGED:
  146.  
  147. #define    LM_CONDITION_ACKNOWLEDGED    (('A'<<24)|('S'<<16)|('D'<<8)|'G')
  148.  
  149. 7. Requesting Registration
  150. -----------------------------------------------------------------------------
  151.  
  152. After defining your message port to be  used  by the LMS to notify you of a
  153. low memory situation and defining a LowMemMsg structure,  you register your
  154. message port and message structure with the ASDG LMS by calling the library
  155. routine ``RegLowMemReq''. 
  156.  
  157. The call takes the following form:
  158.  
  159.     Result = RegLowMemReq(PortName , PtrToLowMemMsg);
  160.       d0                     a0             a1
  161.  
  162. The call will return 0 if all went  well.  This  return  indicates that you
  163. will be receiving low memory warnings through the specified port. If,  how-
  164. ever you do not receive a  0  result  then  something went astray with your
  165. registration request. 
  166.  
  167. Two error results are defined. These are:
  168.  
  169. #define    LM_BADNAME    -1    /* duplication of port name */
  170. #define    LM_NOMEM    -2    /* memory allocation failed */
  171.  
  172. If you receive LM_BADNAME then the ASDG LMS is telling you that someone has
  173. previously registered the  same port  name as  you have  just tried. Simply
  174. change the name and resubmit the request (taking into account the fact that
  175. you might have already allocated a port with the invalid name).
  176.  
  177. The following flow chart indicates a reasonable way to choose a port name:
  178.  
  179.                 Forbid()
  180.                    |
  181.                    |
  182.                      Choose A Name <----------\-----\
  183.                        |                  |     |
  184.                    |                  |     |
  185.                         FindPort              |     |
  186.                    |                  |     |
  187.                    |            (yes) |     |
  188.                  Port Already Defined?--------/     |
  189.                        |                        |
  190.                    | (no)                   |
  191.                    |                        |
  192.                  RegLowMemReq                   |
  193.                        |                        |
  194.                    |            (yes)       |
  195.           (Note 1)---------->Fail?----------------------/
  196.                    |
  197.                    | (no)
  198.                    |
  199.                        CreatePort
  200.                    |
  201.                    |
  202.                 Permit
  203.                    |
  204.                    v
  205.  
  206. Note 1: This can happen since someone may  have DeletePort'ed  their message
  207. port  but  NOT  canceled   their   reservation   with  the  LMS  by  calling 
  208. DeRegLowMemReq.
  209.  
  210. 8. Requesting DeRegistration
  211. -----------------------------------------------------------------------------
  212.  
  213. As part of your program's  exit process  you should cancel your registration
  214. with the LMS. This is  done by calling DeRegLowMemReq with the LMS port name
  215. as the only argument.  If you  do not  call this  routine before exiting AND
  216. some other process still has the LMS  library  open, the memory that the LMS
  217. library allocated to store your registration will not be freed. 
  218.  
  219. However, when the  last  process  that has the LMS library open finally does
  220. close it, all remaining  nodes  (from people who didn't call DeRegLowMemReq)
  221. will be expunged along with the rest of the library.
  222.  
  223. Summary of call:
  224.  
  225.     (void) DeRegLowMemReq(PortName);
  226.                              a0
  227.  
  228. 9. Closing The LMS Library
  229. -----------------------------------------------------------------------------
  230.  
  231. It is absolutely  critical that  your close  the LMS  library before exiting
  232. your program. If you don't,  the  library's open count can never again go to
  233. zero causing  the  library to  be unable  to expunge itself from memory when
  234. otherwise no longer  needed. While the LMS is very compact this is still not
  235. a wise thing to do.
  236.  
  237. The LMS library is closed in the following way:
  238.  
  239.     CloseLibrary(LowMemBase);
  240.  
  241. Note that the long integer LowMemBase must be declared somewhere in your ap-
  242. plication using the above spelling.
  243.  
  244. 10. The lm_flag Again...
  245. -----------------------------------------------------------------------------
  246.  
  247. This chapter is here JUST to remind you that the LMS will look for a specif-
  248. ic value in your lm_flag LowMemMsg field.  If  lm_flag is not LM_CONDITION_-
  249. ACKNOWLEDGED, then the LMS will not send you any more messages.
  250.  
  251. 11. Hints For Using The ASDG LMS Effectively
  252. -----------------------------------------------------------------------------
  253.  
  254. If AllocMem detects that it is going to fail due to lack of memory, it will
  255. run the list  of libraries  calling each library's expunge routine in turn.
  256. The LMS upon having its expunge  routine tickled  will run through its list
  257. of registrations sending off  messages  to each  registered message port in
  258. turn (the last thing you want here is to have LMS wait for a reply so it is
  259. written  specifically NOT  to - so don't reply to any messages that the LMS
  260. may send you).
  261.  
  262. Some calls to AllocMem fail  even  when there's plenty of memory available.
  263. For example, a  request   to  AllocMem  for 2 megabytes of memory on a 512K
  264. Amiga will certainly fail even though there might be 400K still available.
  265.  
  266. To really use the LMS  effectively,  the first thing your program should do
  267. is to actually interrogate the  amount of memory available on the system by
  268. calling AvailMem. Thus, your program can tell the difference between a real
  269. memory emergency and an AllocMem whose goals were unrealistic.
  270.  
  271. 12. About The ASDG LMS
  272. -----------------------------------------------------------------------------
  273.  
  274. The ASDG Low Memory Server was written completely in Manx Assembly Language
  275. by Perry S. Kivolowitz, president of ASDG Incorporated. The LMS was written
  276. as part of the development  of  ASDG's  update to Facc, FaccII. FaccII is a
  277. floppy accelerator  providing performance from floppy disk far in excess of
  278. current hard disks (with some limitations of course).
  279.  
  280. FaccII will use the  LMS  to  determine  when it should begin taking memory
  281. conservation measures. 
  282.  
  283. While FaccII is   a  commercial product, we have decided to release the LMS
  284. for non-commercial distribution (and licensed commercial distribution)  be-
  285. cause we view the LMS as a useful generic tool which we feel the Amiga com-
  286. munity as a whole  would  benefit from  and,  of course, we felt that doing 
  287. this would be in the best interest of ASDG (besides why have everyone write
  288. their own and possibly  have  several  of  them  running  on the machine at 
  289. once?).
  290.  
  291. We feel ASDG has contributed as much to the betterment of the Amiga commun-
  292. ity  as any other vendor or private  contributor. The  ASDG Recoverable Ram
  293. Disk, tutorials in Amazing Computing, and  now  the LMS are examples of our
  294. love and commitment  for  the  Amiga  personal computer and the Amiga using
  295. community. This is our small way of showing that, yes,  we put back in  and
  296. not just take out.
  297.  
  298.